/**
 * @(#)UsuariosManager.java 8/11/2010
 *
 * Copyright (c) 2007-2012 PsiqueWare S.A. de C.V. All Rights Reserved.
 * This software is the proprietary information of PsiqueWare S.A. de C.V.
 * Use is subject to license terms.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * <br/>Usuario : AngelElectrico
 * <br/>Creaci&oacute;n: 8/11/2010 - 06:22:06 PM
 * <br/>
 * <br/>
 * <br/><t5>Cambios :</t5>
 * <br/><b>Fecha | Autor  |  Cambios</b>
 * <ul>
 * <li>8/11/2010 | <a href = "mailto:AngelElectrico@PsiqueWare.com">&Aacute;ngel El&eacute;ctrico</a> | Creaci&oacute;n del Objeto.</li>
 *
 * </ul>
 */

package com.psiqueware.alheli.id;

import com.psiqueware.alheli.dao.EnlaceTransaccional;
import com.psiqueware.alheli.manager.BaseManagerInterface;
import com.psiqueware.alheli.manager.ManagerException;

import java.util.List;

/**
 * Administrador de Usuarios.
 * <br/>Paquete Original: com.psiqueware.alheli.id
 * <br/>Nombre  Original: UsuariosManager
 * <br/>Oprima para ver : <a href="UsuariosManager.java.html"><i>C&oacute;digo Fuente</i> </a>
 *
 * @author <a href="mailto:AngelElectrico@PsiqueWare.com">AngelElectrico</a>
 * @version Revision: 1.1 8/11/2010 06:22:06 PM
 * @noinspection UnusedDeclaration
 */
public interface UsuariosManager extends BaseManagerInterface
{

    /**
     * Devuelve un listado de los {@link Dominio} dados de alta.
     * @return Listado de {@link Dominio}s dados de alta.
     * @throws ManagerException en caso de no poder completar la operaci&oacute;n.
     */
    List<Dominio> listaDominios(final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Crea un {@link Dominio} a partir de su nombre y descripcion.
     * Si ya exist&iacute;a un {@link Dominio} con dicho nombre brotar&aacute; una excepci&oacute;n.
     *
     * @param nombre              del {@link Dominio}.
     * @param descripcion         del {@link Dominio}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return el {@link Dominio} si se encuentra; <code>null</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    Dominio nuevoDominio(final String nombre, final String descripcion, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Devuelve un {@link Usuario} a partir de su identificacion.
     * No deberia importar si es mayusculas o minusculas.
     *
     * @param id                  del {@link Usuario} buscado.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link Usuario} en caso de encontrarlo; <code>null</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    Usuario buscarUsuarioPorId(final Long id, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Devuelve un {@link Dominio} a partir de su id.
     *
     * @param id                  del {@link Dominio}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return el {@link Dominio} si se encuentra; <code>null</code> en caso contrario.
     *
     * @throws ManagerException en caso de no poder completar la operaci&oacute;n.
     */
    Dominio buscaDominioPorId(final Long id, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


    /**
     * Devuelve un {@link Dominio} a partir de su nombre.
     *
     * @param nombre              del {@link Dominio}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return el {@link Dominio} si se encuentra; <code>null</code> en caso contrario.
     *
     * @throws ManagerException en caso de no poder completar la operaci&oacute;n.
     */
    Dominio buscaDominioPorNombre(final String nombre, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


    /**
     * Devuelve ls lista de {@link Usuario}s dados de alta en la aplicaci&oacute;n.
     *
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link List} con {@link Usuario}s; vacia si no se encuentra ninguno.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    List<Usuario> buscaUsuariosRegistrados(final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Devuelve ls lista de {@link Usuario}s dados de alta en la aplicaci&oacute;n.
     *
     * @param dominio             {@link Dominio} cuyos {@link Usuario}s se buscan.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link List} con {@link Usuario}s; vacia si no se encuentra ninguno.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    List<Usuario> buscaUsuariosRegistradosDominio(final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Crea un nuevo Usuario. Para el dominio por defecto (<code>null</code>).
     *
     * @param identificacion      del usuarios. Alias Identificacion, alias UserName. No puede ser <code>null</code> ni repetirse.
     * @param clave               argumento dependiente del sistema; usualmente el id del usuario. Puede ser <code>null</code>.
     * @param titulo              argumento dependiente del sistema. Utilizado para describir al usuario en pantalla o cualquier
     *                            otro prop&oacute;sito general.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return nuevo {@link Usuario}.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    Usuario nuevoUsuario(final String identificacion, final String clave, final String titulo, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Crea un nuevo Usuario.
     *
     * @param identificacion      del usuarios. Alias Identificacion, alias UserName. No puede ser <code>null</code> ni repetirse.
     * @param clave               argumento dependiente del sistema; usualmente el id del usuario. Puede ser <code>null</code>.
     * @param titulo              argumento dependiete del sistema. Utilizado para describir al usuario en pantalla o cualquier
     *                            otro prop&oacute;sito general.
     * @param dominio             {@link Dominio} al que pertenecer&aacute; el {@link Usuario}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return nuevo {@link Usuario}.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    Usuario nuevoUsuario(final String identificacion, final String clave, final String titulo, final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


    /**
     * Crea un nuevo Usuario y su {@link Identificacion}. Para el {@link Dominio} por defecto (<code>null</code>). Para el {@link Dominio} por defecto (<code>null</code>).
     *
     * @param identificacion      del usuarios. Alias Identificacion, alias UserName. No puede ser <code>null</code> ni repetirse.
     * @param clave               argumento dependiente del sistema; usualmente el id del usuario. Puede ser <code>null</code>.
     * @param titulo              argumento dependiete del sistema. Utilizado para describir al usuario en pantalla o cualquier
     *                            otro prop&oacute;sito general.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     * @param autenticacion       para autenticar a esta {@link Persona}.
     *
     * @return nuevo {@link Usuario}.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    Identificacion nuevoUsuario(final String identificacion, final char[] autenticacion, final String clave, final String titulo, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


    /**
     * Crea un nuevo Usuario y su {@link Identificacion}.
     *
     * @param identificacion      del usuarios. Alias Identificacion, alias UserName. No puede ser <code>null</code> ni repetirse.
     * @param clave               argumento dependiente del sistema; usualmente el id del usuario. Puede ser <code>null</code>.
     * @param titulo              argumento dependiete del sistema. Utilizado para describir al usuario en pantalla o cualquier
     *                            otro prop&oacute;sito general.
     * @param dominio             {@link Dominio} al que pertenecer&aacute; el {@link Usuario}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     * @param autenticacion       para autenticar a esta {@link Persona}.
     *
     * @return nuevo {@link Usuario}.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    Identificacion nuevoUsuario(final String identificacion, final char[] autenticacion, final String clave, final String titulo, final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


    /**
     * Elimina el {@link Identificacion} y {@link Usuario}s y dem&aacute;s informaci&oacute;n relacionada
     * a partir de una cadena del {@link Usuario}.
     *
     * @param usuario             a eliminar.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws ManagerException en caso de no poder completar la operaci&oacute;n.
     */
    void eliminarUsuario(final Usuario usuario, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Elimina el {@link Identificacion} y {@link Usuario}s y dem&aacute;s informaci&oacute;n relacionada
     * a partir de una cadena de identificaci&oacute;n. Para el {@link Dominio} por defecto (<code>null</code>).
     *
     * @param identificacion      a eliminar.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws ManagerException en caso de no poder completar la operaci&oacute;n.
     */
    void eliminarIdentificacion(final String identificacion, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Elimina el {@link Identificacion} y {@link Usuario}s y dem&aacute;s informaci&oacute;n relacionada
     * a partir de una cadena de identificaci&oacute;n.
     *
     * @param identificacion      a eliminar.
     * @param dominio             para el cual se elimina la identificaci&oacute;n.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws ManagerException en caso de no poder completar la operaci&oacute;n.
     */
    void eliminarIdentificacion(final String identificacion, final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


    /**
     * Determina si ya se encuentra reservado un nombre de Usuario.
     *
     * @param identificacion      del {@link Identificacion} que se busca
     * @param dominio             {@link Dominio} para el cual se valida la identificaci&oacute;n puede ser <code>null</code> en caso de ser del dominio por defecto.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si el userName ya existe; <code>false</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          si se presenta alg&uacute;n problema accediendo a persistencia.
     */
    boolean isIdentificacionReservada(final String identificacion, final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Devuelve un {@link Usuario} a partir de su identificacion.
     * No deberia importar si es mayusculas o minusculas. Para el {@link Dominio} por defecto (<code>null</code>).
     *
     * @param identificacion      del {@link Usuario} buscado.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link Usuario} en caso de encontrarlo; <code>null</code> en caso contrario.
     *
     * @throws ManagerException si se presenta alg&uacute;n problema al acceder a persistencia.
     */
    Usuario buscarUsuarioPorIdentificacion(final String identificacion, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Devuelve un {@link Usuario} a partir de su identificacion.
     * No deberia importar si es mayusculas o minusculas. Para el {@link Dominio} por defecto (<code>null</code>).
     *
     * @param identificacion      del {@link Usuario} buscado.
     * @param dominio             donde aplica el {@link Usuario}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link Usuario} en caso de encontrarlo; <code>null</code> en caso contrario.
     *
     * @throws ManagerException si se presenta alg&uacute;n problema al acceder a persistencia.
     */
    Usuario buscarUsuarioPorIdentificacion(final String identificacion, final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Cambia la informaci&oacute;n de clave o t&iacute;tulo de un Identificacion.
     *
     * @param usuario             cuya informaci&oacute;n se desea cambiar.
     * @param clave               nueva clave para {@link Usuario}.
     * @param titulo              nuevo titulo para el {@link Usuario}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws ManagerException si se presenta alg&uacute;n problema al acceder a persistencia.
     */
    void cambiarClaveTituloUsuario(final Usuario usuario, final String clave, final String titulo, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


}

